Skip to content

Clarify tool result content visibility#1562

Closed
jayaraman-venkatesan wants to merge 3 commits into
modelcontextprotocol:mainfrom
jayaraman-venkatesan:feature/sep-2200-tool-result-visibility
Closed

Clarify tool result content visibility#1562
jayaraman-venkatesan wants to merge 3 commits into
modelcontextprotocol:mainfrom
jayaraman-venkatesan:feature/sep-2200-tool-result-visibility

Conversation

@jayaraman-venkatesan
Copy link
Copy Markdown
Contributor

@jayaraman-venkatesan jayaraman-venkatesan commented May 6, 2026

feat(sep-2200): align tool result content visibility with SEP-2200

Closes #1552

Summary

Brings the C# SDK into compliance with SEP-2200 — "Clarify tool result content visibility"

SEP-2200 clarifies that CallToolResult.content is model-oriented (may be a prose summary) and CallToolResult.structuredContent is machine-oriented (strict JSON for programmatic consumers). Clients SHOULD prefer content for model context and SHOULD NOT forward both fields verbatim to the LLM. The wire format is unchanged.

What

Behavioural fix McpClientTool.InvokeCoreAsync

Removed result.StructuredContent is null from the gate. The Content-block conversion path now triggers whenever there's no protocol-level info to preserve (IsError=true or non-empty Meta), regardless of whether StructuredContent is also set.

See THIS comment for more info.

- if (result.IsError is not true &&
-     result.StructuredContent is null &&
-     result.Meta is not { Count: > 0 })                                                                                                                                                                        
+ if (result.IsError is not true &&
+     result.Meta is not { Count: > 0 })                                                                                                                                                                        

XML doc updates (no behaviour change)

  • CallToolResult.Content / StructuredContent — model-vs-machine semantics + the SEP-2200 selection rule.
  • [McpServerTool].UseStructuredContent / OutputSchemaType — call out the default JSON-dump behaviour and point to the recommended decoupled-fields pattern.
  • McpServerToolCreateOptions.UseStructuredContent / OutputSchema — same wording mirrored on the options surface.
  • McpClient.CallToolAsync<remarks> explaining which field to forward to the model and which to consume programmatically.
    ### Sample
    New samples/EverythingServer/Tools/WeatherStructuredTool.cs demonstrating the SEP-2200 recommended pattern: returns a CallToolResult with model-friendly prose in Content ("It's 72°F and sunny in Paris …") alongside machine-friendly JSON in StructuredContent ({"city":"Paris","tempF":72,…}), with the schema advertised via OutputSchemaType = typeof(WeatherReading).

Behavioural change call-out

Clients embedding this SDK in IChatClient flows will stop double-feeding content + structuredContent to the LLM.
The default [McpServerTool(UseStructuredContent=true)] JSON-dump-into-both shape is preserved (SEP-2200 explicitly permits it, though considers it suboptimal).

No wire change

SEP-2200 itself is non-wire-breaking: same content, same structuredContent, same types. Only the SDK's consumption of the wire result changed.

Test plan

  • dotnet test tests/ModelContextProtocol.Tests (net10.0): 1887 passed, 0 failed, 5 skipped.
  • Targeted: red-then-green confirmed for StructuredContentTool_PrefersContentBlocksForModel
  • dotnet build src/ModelContextProtocol.Core and dotnet build samples/EverythingServer: 0 warnings, 0 errors across all target frameworks.

…ent vs. structuredContent semantics and add decoupled-fields sample
…ot full CallToolResult) when StructuredContent is also present
@jayaraman-venkatesan jayaraman-venkatesan marked this pull request as ready for review May 6, 2026 02:43
@jayaraman-venkatesan jayaraman-venkatesan changed the title Clarify tool visibility Clarify tool result content visibility May 8, 2026
@jayaraman-venkatesan
Copy link
Copy Markdown
Contributor Author

@mikekistler can you help review this PR?

Copy link
Copy Markdown
Contributor

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This appears to be almost entirely a documentation change. It seems fine but I'm not sure all of this is needed.

In addition, I think we should hold off on merging this until SEP-2200 is accepted.

@jayaraman-venkatesan
Copy link
Copy Markdown
Contributor Author

@mikekistler
As of today (2026-05-25), it's been Closed rather than accepted

While this SEP might improve the semantics, it also causes server authors and client authors to implement different behaviour, including starting to return different content. We feel this is a symptom of an underlying issue with the tools/call interface, that we need to address instead, by allowing polymorphic return types (structured or unstructured), instead of returning both. As a result, we prefer to defer/decline this, while in principle right, in order to focus on fixing the underlying issue in the next spec version

That makes landing this PR awkward in every direction as the changes all normatively cite SEP-2200, which is now incorrect guidance.

I'd lean toward closing this PR and leaving #1552 open to track the future polymorphic-return-types work. Does that match your read, or do you see a scoped subset (e.g. just the XML docs changes) worth keeping?

@mikekistler
Copy link
Copy Markdown
Contributor

I also prefer simply closing this PR and waiting until the dust settles on whatever guidance is deemed appropriate.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SEP-2200: Clarify tool result content visibility

3 participants